home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat4 / rgb.z / rgb
Encoding:
Text File  |  1998-10-20  |  11.4 KB  |  331 lines
  1.  
  2.  
  3.  
  4. RRRRGGGGBBBB((((4444))))                                                                  RRRRGGGGBBBB((((4444))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      rgb - Silicon Graphics rgb image file format
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ggggllll////iiiimmmmaaaaggggeeee....hhhh>>>>
  13.  
  14. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  15.      IRIS image files are used to store 1,2 and 3 dimensional arrays of pixel
  16.      values that contain either 1 or 2 bytes per pixel.  Pixel values are
  17.      signed integers that cover the range 0..255 or -32768..32767 (i.e. 1 or 2
  18.      bytes).  Image files are currently used to store rgb screen dumps, black
  19.      and white images, color index images, as well as colormaps.
  20.  
  21.      The image library provides tools to manipulate these files.  To include
  22.      the image library place the token -limage on the compile line for your
  23.      program.  Also, be sure to include image.h from /usr/include/gl in any
  24.      source files that use these routines.  The following routines provide a
  25.      procedural interface to image files:
  26.  
  27.  
  28.    OOOOppppeeeennnniiiinnnngggg aaaannnndddd CCCClllloooossssiiiinnnngggg aaaannnn IIIImmmmaaaaggggeeee FFFFiiiilllleeee
  29.      IMAGE *iopen(file, mode [, type, dim, xsize, ysize, zsize]) char *file;
  30.      register char *mode; unsigned int type, dim, xsize, ysize, zsize;
  31.  
  32.      Opens an image file for reading or writing and returns a pointer to IMAGE
  33.      in the same style as the UNIX standard i/o library.  A return value of 0
  34.      means the function failed to successfully open the file that was named.
  35.  
  36.  
  37.      To open an image file for reading, iopen should be called with 2
  38.      arguments, the name of the image file to open and a mode of "r".  The
  39.      dimensions of the image may be determined by referencing image->xsize,
  40.      image->ysize, and image->zsize, where image is the value returned by
  41.      iopen.  xsize and ysize are defined in terms of pixels while zsize
  42.      describes the number of channels (i.e. layers) the image contains.
  43.  
  44.      The value of image->dim indicates whether the image is just a single row
  45.      (one dimensional) or is an array of rows (two dimensional) or is an array
  46.      of 2 dimensional images (three dimensional).
  47.  
  48.  
  49.      An rgb image can be thought of as a set of three 2 dimensional images.
  50.      Sometimes this is referred to as a 3 channel image.  An rgb color image
  51.      consists of 3 channels (one channel each for the red green and blue
  52.      components of the image) and is represented as a three dimensional image
  53.      that is xsize by ysize by 3.  A black and white image has one channel and
  54.      is represented as a two dimensional image that is xsize by ysize.
  55.  
  56.  
  57.      Other information may be found in image->name (holds the string that is
  58.      usually the same as the actual image filename), image->colormap (defines
  59.      whether the image is a series of intensity values, or color lookup table
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. RRRRGGGGBBBB((((4444))))                                                                  RRRRGGGGBBBB((((4444))))
  71.  
  72.  
  73.  
  74.      indices, or an actual colormap), image->max (the maximum intensity stored
  75.      in the image), and image->min (the minimum intensity stored in the
  76.      image).
  77.  
  78.  
  79.      To open an image file for writing, iopen should be called with 7
  80.      arguments, the name of the image file to open, and a mode of "w",
  81.      followed by the type, the number of dimensions and the xsize, ysize and
  82.      zsize of the image.  The type indicates how many bytes are stored per
  83.      pixel value, and whether the image file should be run-length encoded.
  84.      Type may be given as RLE(1), RLE(2), VERBATIM(1), or VERBATIM(2).  Run-
  85.      length encoded (RLE) image files are more efficiently stored than
  86.      verbatim files where no compression algorithm is used.  1 or 2 in the
  87.      above specifies how many bytes are used for each pixel in a colormap
  88.      image, or for each channel in an rgb image.  RLE(2) or VERBATIM(2) is
  89.      used to store color index images that contain 12 bits per pixel.  RLE(1)
  90.      is the recommended default for rgb and black and white images.
  91.  
  92.      iclose(image) register IMAGE  *image;
  93.  
  94.      Closes an image file that was open for reading or writing.  All output is
  95.      flushed to the output file, and the output file is closed.
  96.  
  97.  
  98.    RRRReeeeaaaaddddiiiinnnngggg aaaannnndddd WWWWrrrriiiittttiiiinnnngggg aaaannnn IIIImmmmaaaaggggeeee FFFFiiiilllleeee
  99.      The following functions allow pixels to be transferred to and from an
  100.      image file.  These functions provide an interface to an image file that
  101.      is independent of whether the image file happens to be run length
  102.      encoded, and independent of whether it maintains 1 or 2 bytes per pixel.
  103.      putrow(image,buffer,y,z) register IMAGE  *image; unsigned short  *buffer;
  104.      unsigned        y, z;
  105.  
  106.      Writes a row of pixels to the specified image file. The buffer should be
  107.      an array of shorts that contain the pixel values of a colormap image or
  108.      one of the 3 channels of an rgb image.  If the image file maintains
  109.  
  110.      only one byte per pixel, then the values passed in the buffer should be
  111.      in the range 0..255.  The row of the image to be written is given by y,
  112.  
  113.      while z selects which channel of the image to write to.  The first
  114.      channel of the image is channel 0.  A black and white image will have
  115.      only 1 channel while rgb images have 3 channels.  In an rgb image,
  116.  
  117.      channel 0 is used to store red while channel 1 stores green, and channel
  118.      2 stores blue pixel data.  The y argument should be greater than or equal
  119.      to zero and less than the ysize of the image.  The rows of the image file
  120.      may be written in any order.  getrow(image,buffer,y,z) register IMAGE
  121.      *image; unsigned short *buffer; register unsigned int y, z;
  122.  
  123.      Reads a row of pixels from the specified image file.  The buffer should
  124.      be an array of shorts to receive pixel values of a colormap image or one
  125.      of the 3 channels of an rgb image.  The row of the image to be read is
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. RRRRGGGGBBBB((((4444))))                                                                  RRRRGGGGBBBB((((4444))))
  137.  
  138.  
  139.  
  140.      given by y, while z selects which channel of the image to read from.  The
  141.      first channel of a image is channel 0.  A black and white image will have
  142.      only 1 channel, while an rgb image will have 3.  The y argument should be
  143.      greater than or equal to zero and less than the ysize of the image.  The
  144.      rows of the image file may be read in any order.
  145.  
  146.  
  147.      Miscellaneous Functions isetname(image,name) IMAGE *image; char *name;
  148.  
  149.      Copies the character string name into the name field of the image file.
  150.  
  151.      NOTE:  handling names when processing two files together is not well
  152.      supported and is not encouraged.  isetcolormap(image,colormap) IMAGE
  153.      *image; int colormap;
  154.  
  155.      Tells ipaste and some printing utilities whether the pixel values should
  156.      be interpreted as color-index pixels or intensities.  A gray scale image
  157.      consists of one channel of intensities, while an rgb image has three
  158.      independent channels of pixel intensities, one channel for each red,
  159.      green and blue intensities.  The argument colormap may be one of
  160.      following three values: CM_NORMAL is the default indicating that the
  161.      pixels are intensity values.  0 is black and a value of 255 in the image
  162.      is white. Black and white images and rgb images are stored with
  163.      CM_NORMAL.  CM_SCREEN indicates that the pixels were copied from the
  164.      screen and must be transformed by a color map to be meaningful.
  165.      Colormaps can also be stored in image files.  CM_COLORMAP means that the
  166.      pixels in the image file represent a color map
  167.  
  168.  
  169.    AAAAnnnn EEEExxxxaaaammmmpppplllleeee
  170.      The following example shows how to open an image file and read its
  171.      contents.  More examples may be found in
  172.      /usr/people/4Dgifts/iristools/imgtools.
  173.  
  174.  
  175.         /*
  176.          *      readimage - Read an image file and print its pixel values.
  177.          *
  178.          *      To compile:  cc readimage.c -o readimage -limage
  179.          *
  180.          *                              Paul Haeberli - 1991
  181.          */
  182.         #include <gl/image.h>
  183.  
  184.         main(argc,argv)
  185.         int argc;
  186.         char **argv;
  187.         {
  188.             IMAGE *image;
  189.             int x, y, z;
  190.             short *rbuf, *gbuf, *bbuf;
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. RRRRGGGGBBBB((((4444))))                                                                  RRRRGGGGBBBB((((4444))))
  203.  
  204.  
  205.  
  206.         /* print usage message */
  207.             if( argc<2 ) {
  208.                 fprintf(stderr,"usage: readimage infile0);
  209.                 exit(1);
  210.             }
  211.  
  212.         /* open the image file */
  213.             if( (image=iopen(argv[1],"r")) == NULL ) {
  214.                 fprintf(stderr,"readimage: can't open input file %s0,argv[1]);
  215.                 exit(1);
  216.             }
  217.  
  218.         /* print a little info about the image */
  219.             printf("Image x and y size in pixels: %d
  220.         %d0,image->xsize,image->ysize);
  221.             printf("Image zsize in channels: %d0,image->zsize);
  222.             printf("Image pixel min and max: %d %d0,image->min,image-max);
  223.  
  224.         /* allocate buffers for image data */
  225.             rbuf = (short *)malloc(image->xsize*sizeof(short));
  226.             gbuf = (short *)malloc(image->xsize*sizeof(short));
  227.             bbuf = (short *)malloc(image->xsize*sizeof(short));
  228.  
  229.         /* check to see if the image is B/W or RGB */
  230.             if(image->zsize == 1) {
  231.                 printf("This is a black and write image0);
  232.                 for(y=0; y<image->ysize; y++) {
  233.                     getrow(image,rbuf,y,0);
  234.                     printf("row %d: ",y);
  235.                     for(x=0; x<image->xsize; x++)
  236.                         printf("%d |",rbuf[x]);
  237.                     printf("0);
  238.                 }
  239.             } else if(image->zsize >= 3) {  /* if the image has alpha zsize is 4 */
  240.                 printf("This is a rgb image0);
  241.                 for(y=0; y<image->ysize; y++) {
  242.                     getrow(image,rbuf,y,0);
  243.                     getrow(image,gbuf,y,1);
  244.                     getrow(image,bbuf,y,2);
  245.                     printf("row %d: ",y);
  246.                     for(x=0; x<image->xsize; x++)
  247.                         printf("%d %d %d |",rbuf[x],gbuf[x],bbuf[x]);
  248.                     printf("0);
  249.                 }
  250.             }
  251.         }
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. RRRRGGGGBBBB((((4444))))                                                                  RRRRGGGGBBBB((((4444))))
  269.  
  270.  
  271.  
  272. BUGS
  273.      There are too many video image file formats.
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.